home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 5 / The 640 Meg Shareware Studio CD-ROM Volume V (Data Express)(1994).ISO / amiga / rxdssp14.lha / RexxDosSupport.doc < prev    next >
Text File  |  1994-03-17  |  14KB  |  433 lines
  1. TABLE OF CONTENTS
  2.  
  3. RexxDosSupport.library/--Disclaimer--
  4. RexxDosSupport.library/--background--
  5. RexxDosSupport.library/--history--
  6. RexxDosSupport.library/--installation--
  7. RexxDosSupport.library/DeleteVar
  8. RexxDosSupport.library/Fault
  9. RexxDosSupport.library/GetVar
  10. RexxDosSupport.library/MatchPattern
  11. RexxDosSupport.library/ParsePattern
  12. RexxDosSupport.library/ReadArgs
  13. RexxDosSupport.library/SetVar
  14. RexxDosSupport.library/--Disclaimer--   RexxDosSupport.library/--Disclaimer--
  15.  
  16. Disclaimer
  17. ----------
  18.  
  19.    Permission is granted to make and distribute verbatim copies  of  this
  20. manual provided the copyright  notice  and  this  permission  notice  are
  21. preserved on all copies.
  22.  
  23. COPYRIGHT
  24.  
  25.    Copyright (C) 1994 by hartmut Goebel
  26.  
  27.    No program, document, data file or  source  code  from  this  software
  28. package, neither in whole nor in part, may be included or used  in  other
  29. software packages unless it is authorized by a  written  permission  from
  30. the author.
  31.  
  32.  
  33. NO WARRANTY
  34.  
  35.    There is no warranty for this software package.  Although  the  author
  36. has tried to prevent errors, he can't guarantee that the software package
  37. described in this document is 100% reliable. You are therefore using this
  38. material at your own risk. The author cannot be made responsible for  any
  39. damage which is caused by using this software package.
  40.  
  41.  
  42. DISTRIBUTION
  43.  
  44.    This software package is freely distributable. It may be  put  on  any
  45. media which is used for the distribution of free  software,  like  Public
  46. Domain disk collections, CDROMs, FTP servers or bulletin board systems.
  47.  
  48.    In  order  to  ensure  the  integrity  of   this   software   package,
  49. distributors should use the original archive file  RexxDosSupport1_4.lha.
  50. The author cannot be  made  responsible  if  this software  package   has
  51. become unusable due to modifications of  the  archive  contents   or   of
  52. the archive file itself.
  53.  
  54.    There is no limit on the costs  of  the  distribution,  e.g.  for  the
  55. media, like floppy disks, streamer tapes or compact disks, or the process
  56. of duplicating. Such limits have been proven to be harmful to the idea of
  57. freely distributable software, e.g. instead of reducing the price of  the
  58. floppy disk below the limit, the software was  simply  removed  from  the
  59. master disk.
  60.  
  61.    Although the author does not impose any limit on the  distribution  of
  62. this software package, he would like to express his personal opinions  on
  63. this matter:
  64.  
  65.    * This software package should be made available to everyone  free  of
  66.      charge whenever it is possible.
  67.  
  68.    * If you have acquired this software package under  normal  conditions
  69.      from a Public Domain dealer on a floppy disk at a price higher  than
  70.      5DM or US $5, then you have definitely paid too much.  Please  don't
  71.      support this improper profit making  any  longer  and  switch  to  a
  72.      cheaper source as soon as possible.
  73.  
  74.  
  75. USAGE RESTRICTIONS
  76.  
  77.    No program, document, data file or  source  code  from  this  software
  78. package, neither in whole nor in part, may be used on any  machine  which
  79. is used
  80.  
  81.    * for the research, development, construction, testing  or  production
  82.      of weapons or other military applications. This  also  includes  any
  83.      machine which is  used  in  the  education  for  any  of  the  above
  84.      mentioned purposes.
  85.  
  86.    * by people who accept, support or use violence against other  people,
  87.      e.g. citizens from foreign countries.
  88.  
  89. RexxDosSupport.library/--background--   RexxDosSupport.library/--background--
  90.  
  91.                 RexxDosSupport.library 1.4
  92.                 ==========================
  93.  
  94.             Copyright (C) 1994 by hartmut Goebel
  95.  
  96.  
  97.    After programming ARexx script for quite a while, I missed some
  98.    function found in dos.library --  especially access to
  99.    environment variables and the comfortable argument parsing. Since
  100.    there seamed to be no ARexx function library which implements
  101.    this functions, I decited to write my own. And here it is.
  102.  
  103.    This are the functions handled by this library.
  104.  
  105.    ╖ ReadArgs()
  106.    ╖ GetVar(), SetVar(), DeleteVar()
  107.    ╖ ParsePattern() MatchPattern() - even case-insensitive
  108.    ╖ Fault()
  109.  
  110.    Enjoy it!
  111.    +++hartmut
  112.  
  113. RexxDosSupport.library/--history--         RexxDosSupport.library/--history--
  114.  
  115.   1.4  01 Feb 1994
  116.        ╖ only significant part of parsed pattern is copied
  117.          into the ARexx Argstring
  118.  
  119.   1.3  23 Jan 1994
  120.        ╖ uses module RxLibsSupport [hG]
  121.  
  122.   1.2  18 Jan 1994
  123.        ╖ finished dokumentation
  124.        ╖ UnsetVar() - like shell commnad - renamed to
  125.          DeleteVar() - like in dos.library
  126.        ╖ SetVar() no longer accepts option "Binary"
  127.  
  128.   1.1  16 Jan 1994
  129.        initial release
  130.  
  131. RexxDosSupport.library/--installation--RexxDosSupport.library/--installation--
  132.  
  133.    To use RexxDosSupport.library, just copy is to yout LIBS:
  134.    directory. That's all.
  135.  
  136.    The LVO for the ARexx-Dispatcher is -30.
  137.        NB: it's the only LVO for this library :-)
  138.  
  139.    So, in every ARexx-Script you want to use RexxDosSupport.library,
  140.    insert
  141.  
  142.       call addlib("RexxDosSupport.library",0,-30)
  143.  
  144.    somewhere before the first call to one of the routines
  145.    implemented in this library.
  146.    Since ARexx does not check whether the lib can be opened but only
  147.    inserts the name into a list, the result value from addlib() can
  148.    be ignored in most cases. The value would be interesting to check
  149.    if the added note will require the same library version, but I
  150.    don't know how to find this out.
  151.  
  152. RexxDosSupport.library/DeleteVar             RexxDosSupport.library/DeleteVar
  153.  
  154.    NAME
  155.        DeleteVar -- Deletes a local or environment variable
  156.  
  157.    SYNOPSIS
  158.        success = DeleteVar( name, [ "Local" | "Global" ] )
  159.  
  160.    FUNCTION
  161.        Deletes a local or environment variable.
  162.  
  163.    INPUTS
  164.        name     - variable name.  Note variable names follow
  165.                   filesystem syntax and semantics.
  166.        "Global" - tries to get a global env variable.
  167.        "Local"  - tries to get a local variable.
  168.  
  169.                 The default is to delete a local variable if found, otherwise
  170.                 a global environment variable if found.
  171.  
  172.    RESULT
  173.        success - If TRUE, the variable was sucessfully deleted,
  174.                  FALSE indicates failure.
  175.  
  176.    SEE ALSO
  177.        GetVar(), SetVar(), dos.library/DeleteVar()
  178.  
  179. RexxDosSupport.library/Fault                     RexxDosSupport.library/Fault
  180.  
  181.    NAME
  182.        Fault -- Returns the text associated with a DOS error code
  183.  
  184.    SYNOPSIS
  185.        string = Fault( code, header )
  186.  
  187.    FUNCTION
  188.        This routine obtains the error message text for the given
  189.        error code. The header is prepended to the text of the error
  190.        message, followed by a colon. By convention, error messages
  191.        should be no longer than 80 characters, and preferably no
  192.        more than 60.
  193.  
  194.        The value returned by IoErr() (not available in this library)
  195.        is set to the code passed in. If there is no message for the
  196.        error code, the message will be "Error code <number>\n".
  197.  
  198.        The string will be empty if the code passed in was 0.
  199.  
  200.    INPUTS
  201.        code   - Error code
  202.        header - header to output before error text
  203.  
  204.    RESULT
  205.        string - error massage as described above.
  206.  
  207.        RC (rexx variable) - 5 when error message is empty
  208.                             0 otherwise
  209.  
  210.    SEE ALSO
  211.        dos.library/Fault(), dos.library/IoErr()
  212.  
  213. RexxDosSupport.library/GetVar                   RexxDosSupport.library/GetVar
  214.  
  215.    NAME
  216.        GetVar -- Returns the value of a local or global variable
  217.  
  218.    SYNOPSIS
  219.        string = GetVar( name, ["Local" | "Global"], ["Binary"] )
  220.  
  221.    FUNCTION
  222.        Gets the value of a local or environment variable.  It is advised to
  223.        only use ASCII strings inside variables, but not required.  This stops
  224.        putting characters into the destination when a \n is hit, unless
  225.        "Binary" is specified.  (The \n is not stored in the buffer.)
  226.  
  227.    INPUTS
  228.        name     - variable name.
  229.        "Global" - tries to get a global env variable.
  230.        "Local"  - tries to get a local variable.
  231.        "Binary" - don't stop at \n
  232.                   in this mode the string returned is not null terminated
  233.  
  234.                 The default is to try to get a local variable first,
  235.                 then to try to get a global environment variable.
  236.  
  237.    RESULT
  238.        string - contents of the variable
  239.  
  240.        RC (rexx variable) - 5 when variable does not exist,
  241.                             0 otherwise
  242.  
  243.    EXAMPLE
  244.        /* */
  245.        username = GetVar("username")
  246.        if RC = 5 then
  247.          say "Variable 'username' is not set"
  248.        else
  249.          say "Variable 'username' is" username
  250.  
  251.    NOTES
  252.       contents may be max. 512 char.
  253.  
  254.    BUGS
  255.        Due to a bug in dos.library, binary global vars will be null
  256.        terminated in V37, V38.
  257.  
  258.    SEE ALSO
  259.      SetVar(), DeleteVar(), dos.library/GetVar()
  260.  
  261. RexxDosSupport.library/MatchPattern       RexxDosSupport.library/MatchPattern
  262.  
  263.    NAME
  264.        MatchPattern --  Checks for a pattern match with a string
  265.  
  266.    SYNOPSIS
  267.        match = MatchPattern(pattern, string, ["Nocase"], ["Parsed"] )
  268.  
  269.    FUNCTION
  270.        Checks for a pattern match with a string.
  271.        This routine is case-sensitive by default. Use option
  272.        "NoCase" for case-insensitve matching.
  273.  
  274.        Use option "Parsed" to indicate that pattern has already been
  275.        tokenized using ParsePattern(). Make sure to use or use not
  276.        "NoCase" for both function.
  277.  
  278.    INPUTS
  279.        pattern  - pattern string to match
  280.        string   - string to match against given pattern
  281.        "Nocase" - match should be case-insensitve
  282.        "Parsed" - pattern has already been parsed using ParsePattern()
  283.  
  284.    RESULT
  285.        match - success or failure of pattern match.
  286.  
  287.    SEE ALSO
  288.        ParsePattern(), dos.library/MatchPattern(),
  289.        dos.library/MatchPatternNoCase()
  290.  
  291. RexxDosSupport.library/ParsePattern       RexxDosSupport.library/ParsePattern
  292.  
  293.    NAME
  294.        ParsePattern -- Create a tokenized string for MatchPattern()
  295.  
  296.    SYNOPSIS
  297.        token = ParsePattern( pattern, ["NoCase"] )
  298.  
  299.    FUNCTION
  300.        Tokenizes a pattern, for use by MatchPattern().  Also indicates
  301.        if there are any wildcards in the pattern (i.e. whether it might match
  302.        more than one item).
  303.  
  304.        For a description of the wildcards, see dos.library/ParsePattern().
  305.  
  306.    INPUTS
  307.        pattern  - unparsed wildcard string to search for.
  308.  
  309.    RESULT
  310.        token    - output string, tokenized version of input.
  311.  
  312.        RC (rexx variable) - 5 when does not contain wildcards
  313.                             0 otherwise
  314.  
  315.    BUGS
  316.        Since is't not clear wether the resulting token may contain
  317.        null charakters, the returned string is always
  318.        2 * Length(pattern) + 2 bytes long.
  319.  
  320.    SEE ALSO
  321.        ParsePattern(), dos.library/ParsePattern(),
  322.        dos.library/ParsePatternNoCase()
  323.  
  324. RexxDosSupport.library/ReadArgs               RexxDosSupport.library/ReadArgs
  325.  
  326.    NAME
  327.        ReadArgs -- Parse argument string using Dos/ReadArgs()
  328.  
  329.    SYNOPSIS
  330.        okay = ReadArgs( arguments, template, [stem] )
  331.  
  332.    FUNCTION
  333.        Parses an argument string according to a template. See
  334.        dos.library/ReadArgs() for details and describtion of the
  335.        template.
  336.  
  337.        This function supports the following template options:
  338.  
  339.        /S - Switch.  Resulting variable will be either true (1) or
  340.             false (0).
  341.        /N - Number.
  342.        /M - Multiple strings.  See below for further information.
  343.  
  344.        /K - Keyword.      }
  345.        /A - Required.     }  handled by dos
  346.        /F - Rest of line. }
  347.  
  348.        /T (toggle) is not supported, since handling this would be a
  349.        large turnover with small profit.
  350.  
  351.    INPUTS
  352.        arguments - the string to be parsed
  353.        template  - dos.library/ReadArgs()-style like template
  354.        stem      - stem prefix for resulting variables (optional)
  355.  
  356.    RESULT
  357.        okay  - boolean value indicating success.
  358.  
  359.        RC (rexx variable) - contains the dos error code if the
  360.                function was not successfull. This can can directly
  361.                be used as input for Fault().
  362.  
  363.        For each item in the template which has a corresponding
  364.        argument, a Rexx variable will be created. The variable's
  365.        name is the item's name prefixed by the stem name (if given).
  366.  
  367.        Items with option /M will result in a stem variable with a
  368.        .COUNT node containing the number of elements. If no fitting
  369.        arguments is passed, .COUNT will be zero.
  370.        The entries will be in stem nodes .0 to .n (where n is
  371.        .COUNT-1).
  372.  
  373.    EXAMPLE
  374.        /* ReadArgsExample.rexx */
  375.        /* AddLib() here */
  376.  
  377.        parse arg args /* get the arguments w/o ARexx-Parsing */
  378.  
  379.        template = "Files/M,Method/K,MinSize/K/N,Test/S"
  380.  
  381.        /* set defaults */
  382.        Method = "NUKE"; MinSize = 512;
  383.  
  384.        /* no stem given: results are assigned to simple variables */
  385.  
  386.        if ReadArgs(args,template) then
  387.          say 'Method =' method '  MinSize =' MinSize '  Test =' test
  388.          do i = 0 by 1 for file.count
  389.            say name.1
  390.          end
  391.  
  392.        /* stem given: results are assigned to stem variable */
  393.        /* since the default values are set as non-stem variables,
  394.         * they are not overwritten by the following call even if
  395.         * given
  396.         */
  397.  
  398.        if ReadArgs(input,template,"args.") then
  399.          say 'Method =' args.method '  MinSize =' args.MinSize ' Test =' args.test
  400.          do i = 0 by 1 for args.file.count
  401.            say args.name.1
  402.          end
  403.  
  404.    SEE ALSO
  405.       Fault(), dos.library/ReadArgs()
  406.  
  407. RexxDosSupport.library/SetVar                   RexxDosSupport.library/SetVar
  408.  
  409.    NAME
  410.        SetVar -- Sets a local or environment variable
  411.  
  412.    SYNOPSIS@{ub}
  413.        success = SetVar( name, ["Local" | "Global"] )
  414.  
  415.    FUNCTION
  416.        Sets a local or environment variable.  It is advised to only use
  417.        ASCII strings inside variables, but not required.
  418.  
  419.    INPUTS
  420.        name     - variable name.
  421.        "Global" - tries to get a global env variable.
  422.        "Local"  - tries to get a local variable.
  423.  
  424.                The default is to set a local environment variable.
  425.  
  426.    RESULT
  427.        success - If non-zero, the variable was sucessfully set, FALSE
  428.                  indicates failure.
  429.  
  430.    SEE ALSO
  431.      GetVar(), DeleteVar(), dos.library/SetVar()
  432.  
  433.